COGugaison.Rmd

---
title: "Apprendre les principales fonctionnalités de COGugaison"
author: "antuki"
output: rmarkdown::html_vignette
fig_caption: yes
vignette: >
  %\VignetteIndexEntry{Vignette Title}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

## Introduction à COGugaison


Nous allons balayer dans cette vignette les principales fonctionnalités du package `COGugaison`. 

Le découpage des territoires français, en particulier les communes, n'est pas un phénomène immuable. Chaque année certaines communes changent de codes, ou bien de nom, fusionnent ou encore se divisent. Certains périmètres supra-communaux changent également, comme celui des cantons qui a été récemment redéfini. C'est à l'Insee que revient le suivi de ces changements afin d'établir chaque année le code officiel géographique (COG).

Ce package R a alors pour objectif global de manipuler des données communales produites à différents millésimes et de les agréger à différents niveaux supra-communaux. Plus précisément, il permet actuellement de : 

- détecter le millésime du code officiel géographique d'une table de données communales : fonction `COG_akinator`, faire un diagnostic de COG plus détaillé avec `diag_COG` et apparier une liste de communes d'une base de données avec celle du COG d'un millésime donné avec `apparier_COG`
- visualiser les modifications communales (fusions, défusions, changements de codes ou de noms) qui ont eu lieu entre deux dates : `modifications_communales`  
- visualiser sur un graphique interactif la trajectoire d'une commune donnée, c'est-à-dire toutes les modifications qui ont eu lieu depuis 1968 : `trajectoire_commune` et `trajectoire_commune_shiny`.
- transformer des tables de données numériques en géographie au premier janvier d'une année souhaitée : `changement_COG_varNum`. 
- transformer des typologies de communes en géographie au premier janvier d'une année souhaitée en ayant le choix entre plusieurs hypothèses de classement en cas de fusion de communes de classes différentes (attribuer une unique classe à toutes les communes fusionnées, attribuer la classe qui contient le plus de population, définir une classe absorbante, une classe absorbée ou une classe spécifique aux regroupements de plusieurs communes de classes différentes) : `changement_COG_typo`. Il est également possible d'isoler dans une table les communes fusionnées appartenant à des classes différentes : `changement_COG_typo_details`.
- permettre d'agréger les tables de données communales à de nombreux échelons supra-communaux administratifs (EPCI, arrondissements, cantons-villes, départements, régions) ou d'étude (bassins de vie, zones d'emploi, unités urbaines, aires urbaines) : `nivsupra`. 
- gérer des cas particuliers comme les codes Insee des communes corses (`modification_Corse`) ou des arrondissements municipaux de Paris, Lyon, et Marseille (`enlever_PLM`) ou encore l'ancienne commune de l'Oudon (`modification_Oudon`)

Il est important de souligner que les données utilisées ici s'appuient sur des tables publiées par l'Insee : 

- [l'historique des géographies communales](https://www.insee.fr/fr/information/2666684#titre-bloc-11) 
- [les tables d'appartenance des communes aux différents niveaux géographiques](https://www.insee.fr/fr/information/2028028) 

Il est évidemment conseillé de se référer aux données officielles de l'Insee en cas de doute sur un résultat.  

Commençons par installer le package `COGugaison` et à le charger dans R. 
 
```{r, fig.show='hold'}
#devtools::install_github("antuki/COGugaison")
library(COGugaison)
```

Le millésime le plus récent contenu dans le package peut être visualisé de la manière suivante : 

```{r, fig.show='hold'}
COGugaison:::annee_ref
```

## Les bases de données utiles dans COGugaison

En plus de contenir des fonctions permettant la gestion des codes officiels géographiques, COGugaison contient également, dans des Rdata, des bases de données qui peuvent vous être également utiles par ailleurs.

> - COG

Ce Rdata contient des data.frame (tables de données) intitulés COGXXXX, XXXX étant à remplacer par une année de COG donnée. Les tables intitulées COGXXXX_insee correspondent à des tables selon le COG pris en compte par l'Insee dans la diffusion de ses données (qui est presque identique au COG à quelques exceptions près listées dans la documentation).

```{r, fig.show='hold'}
head(COG2017)
```

Les variables des tables sont les suivantes : 
 
- CODGEO contient le code Insee des communes
- LIBGEO contient le nom des communes
- POP contient la population de référence de la commune selon l'année du COG

> - TABLES_PASSAGE

Ce Rdata contient des data.frame intitulées PASSAGE_XXXX_YYYY, XXXX et YYYY étant à remplacer par des années de COG données. Il s'agit de tables de passages permettant de passer d'un COG à un autre (plus récent ou plus ancien). Le suffixe "_insee" correspond également à des tables qui tiennent compte des COG pris en compte par l'Insee. 

```{r, fig.show='hold'}
head(PASSAGE_2015_2016_insee)
```

Les variables des tables sont les suivantes : 

- codXXXX : code Insee de la commune de départ
- codYYYY : code Insee de la commune d'arrivée
- annee : année de la modification
- typemodif : type de modification communale (f = fusion, d = défusion, c= changement de code). 
- ratio : poids de répartition des effectifs en cas de défusion (vaut 1 sinon). Ce poids est proportionnel à la population des communes défusionnées. 

> - DATA_SUPRACOM

Ce Rdata contient, pour chaque année depuis 2014, deux data.frame intitulées table_supracom_20XX et libelles_supracom_20XX qui correspondent aux [tables d'appartenance des communes aux différents niveaux géographiques](https://www.insee.fr/fr/information/2028028) produites par l'Insee (cliquez sur le lien pour voir la documentation sur les variables présentes). La première table associe chaque code communal insee aux niveaux supra-communaux associés (en COG le plus actuel, actuellement 2017) et la seconde indique les libellés de ces différents niveaux supra-communaux. 

```{r, fig.show='hold'}
head(table_supracom_2017)
head(libelles_supracom_2017)
```

> - HISTORIQ_MODIF_COM

Ce Rdata contient un data.frame intitulé historiq qui correspond à [l'historique des géographies communales](https://www.insee.fr/fr/information/2666684#titre-bloc-11) produit par l'Insee (cliquez sur le lien pour voir la documentation sur les variables présentes). La dernière édition de ce fichier date de 2018 car l'Insee a changé le format de mise à disposition de cette base en 2019 et cette mise à jour n'a pas encore été effectuée dans le package. 


## Quel code officiel géographique est utilisé ? 

Nous allons maintenant manipuler une table exemple incluse dans le package, la table `exemple_popcom` qui contient comme variables le code géographique de la commune (CODGEO), son nom (LIBGEO), sa population en 2012 (P12_POP), sa superficie (SUPERF) ainsi que deux typologies de territoires générées aléatoirement (typoA et typoB). Il faut veiller à ce que les variables numériques soient au bon format dans R et que les typologies et identifiants soient au format caractère (si ce n'est pas le cas, il faudra les transformer avec les fonctions *as.numeric* et *as.character*).

```{r, fig.show='hold'}
head(exemple_popcom)
str(exemple_popcom)
```

### `COG_akinator`

La fonction `COG_akinator` permet de donner des pistes à l'utilisateur sur le code officiel géographique (COG) utilisé dans sa table de données communales, c'est-à-dire de savoir si la liste de communes utilisée correspond à la liste officiel au premier janvier de 2017 ? de 2016 ? ou d'une autre année. 

Le paramètre *donnees_insee* vaut TRUE si les données manipulées sont produites par l'Insee. En effet, quelques rares modifications communales (la défusion des communes Loisey et Culey au 1er janvier 2014 par exemple) ont été prises en compte dans les bases de données communales de l'Insee plus tard que la date officielle (se référer à la documentation de la fonction pour plus de précisions).

```{r, fig.show='hold'}
COG_akinator(vecteur_codgeo = exemple_popcom[,1], donnees_insee = TRUE)
```

En l'occurrence la liste de communes utilisée dans cette table correspond à la liste des communes au 1er janvier 2014. 

### `apparier_COG`

Une fois que le COG d'une base de données est détecté, ou bien si justement le COG n'arrive pas à être détecté par la fonction `COG_akinator`, il est possible d'utiliser la fonction `apparier_COG` pour comparer la liste des communes présente dans une table de données avec le COG d'un millésime donné.

```{r, fig.show='hold'}
COG_akinator(exemple_popcom$CODGEO, donnees_insee = TRUE)
apparier_COG(vecteur_codgeo = c(exemple_popcom[which(exemple_popcom$CODGEO!="01001"),1],"XXXXX"),
             donnees_insee = TRUE, COG = 2014)
appariement <- apparier_COG(vecteur_codgeo = c(exemple_popcom[which(exemple_popcom$CODGEO!="01001"),1],"XXXXX"),
                            donnees_insee = TRUE, COG = 2014)
cat(appariement$absent_de_bdd)
cat(appariement$absent_de_COG)
# regarder le libellé des communes présentes dans le COG mais pas dans la base de données
COG2014_insee[which(COG2014_insee$CODGEO %in% appariement$absent_de_bdd),c(1,2)]
```

### `diag_COG`

Enfin, la fonction `diag_COG` permet de vous outiller encore davantage. Elle réalise un diagnostic complet du ou des COG présents dans votre base de données. 

```{r, fig.show='hold'}
diagnostic <- diag_COG(exemple_popcom)
head(diagnostic)
```

Ici le diagnostic nous montre que la base de données est bien construite puisqu'elle ne comporte que des codes communes d'une même année, 2014. 

Mais cette fonction permet également de diagnostiquer des bases de données qui comportent des mix entre plusieurs COG (oh, horreur !) comme dans l'exemple ci-dessous : 

```{r, fig.show='hold', include=FALSE}
library(dplyr)
```


```{r, fig.show='hold', eval=FALSE}
library(dplyr)
```

```{r, fig.show='hold'}
exemple_popcom_deforme <- exemple_popcom %>% 
  add_row(CODGEO = c(rep("01001",5),"76601","75101",NA,"98756","ZZZZZ"))
diagnostic2 <- diag_COG(exemple_popcom_deforme)
```

La fonction `diag_COG` ne reconnaissant pas le COG, elle identifie pour chaque ligne de la table, l'année la plus récente d'apparition de la commune dans les tables de COG.

Toutefois, lorsque le COG est relativement ancien, comme ici 2014, cette sortie par défaut ne permet pas de réaliser diagnostic de COG utile. Il peut alors être utile de faire une **hypothèse préalable sur le COG initial de la table**, en utilisant notamment la fonction `COG_akinator` puis le paramètre `hypothese_COG` de la fonction `diag_COG` comme ci-après.

```{r, fig.show='hold'}
COG_akinator(exemple_popcom_deforme$CODGEO)
diagnostic3 <- diag_COG(exemple_popcom_deforme, hypothese_COG = 2014)
```

La sortie est alors davantage conforme aux souhaits de l'utilisateur. Une commune a été identifiée comme étant de COG2017 et est à expertiser. Il s'agit de la commune 76601 qui est issue d'une scission ayant eu lieu en 2017. 

## Visualiser les modifications communales

La fonction `trajectoire_commune` permet d'observer sur un diagramme interactif la trajectoire d'une commune depuis 1968 (aucun changement, fusions, défusions ou changements de codes).

Le paramètre *codgeo* est une chaîne de 5 caractères qui indique le code Insee de la commune considérée et le paramètre *COG* indique l'année de COG de la communes considérée.

La fonction `trajectoire_commune_shiny` lance une application shiny qui permet de sélectionner la commune pour laquelle vous souhaitez observer ses modifications depuis 1968.

```{r, fig.show='hold',warning=F,error=F, message=FALSE}
# Ici, nous allons observer sur un graphique interactif la trajectoire de la commune ayant pour code 01003 en 1968
# (fusion avec 2 autres communes le 1er janvier 1974)
trajectoire_commune("01003", 1968, donnees_insee = FALSE)
# Cette fonction lance une application shiny permettant d'observer toutes les trajectoires des communes.
#trajectoire_commune_shiny()
```

La fonction `modifications_communales` permet, comme son nom l'indique, de visualiser les modifications communales (fusions, défusions, changements de codes ou de noms) qui ont eu lieu entre deux dates. Ici entre le 01/01/2014 et le 01/01/2015. Cette fonction est encore en cours de développement il est donc possible que certains évènements ne soient pas encore pris en compte. Il ne faut pas hésiter à le signaler. 

```{r, fig.show='hold'}
modifs <- modifications_communales(date_debut = "01-01-2014", date_fin = "01-01-2015")
cat(modifs$fusions)
cat(modifs$defusions)
cat(modifs$changements_codes)
cat(modifs$changements_noms)
```


## Transformer des variables numériques en autre géographie


La fonction `changement_COG_varNum` permet de transformer des tables de données numériques communales en géographie au premier janvier d'une année souhaitée.

Ici, nous allons transformer les variables numériques de la table *exemple_pop* afin de récupérer les données de population et de superficie des communes au 1er janvier 2017 (au lieu de 2014).

```{r, fig.show='hold'}
exemple_popcom_COG2017_num <- changement_COG_varNum(table_entree = exemple_popcom, annees = c(2014:2017),
                                                    agregation = TRUE, libgeo = TRUE, donnees_insee = TRUE)
head(exemple_popcom_COG2017_num)
```

Le paramètre *agregation* vaut TRUE si la table souhaitée doit sommer toutes les lignes qui concernent une même commune et FALSE si l'on souhaite volontairement conserver les doublons dans les codes commune (dans les tables de flux par exemple, cf. plus bas). Le paramètre *libgeo* vaut TRUE si l'on veut rajouter dans la table une colonne nommée "nom_commune" qui indique le nom de la commune issu du code officiel géographique et FALSE sinon. 


## Transformer des typologies en autre géographie


La fonction `changement_COG_typo` permet de transformer des typologies de communes en géographie au premier janvier d'une année souhaitée. Ici nous allons transformer les deux typologies (typoA et typoB) de la table *exemple_pop* en géographie communale au 1er janvier 2017 (au lieu de 2014).

Ici, l'hypothèse de classement en cas de fusion de communes (*methode_fusion*) choisie est celle d'une classe spécifique (*methode_difference*, classe appelée *mot_difference*="differents") aux regroupements de plusieurs communes de classes différentes. Les autres hypothèses possibles auraient pu être l'hypothèse du maximum de population *methode_max_pop*, de classe absorbée *methode_classe_absorbee*, de classe absorbante *methode_classe_absorbante* ou d'indiquer un nom de classe spécifique pour toutes les communes qui ont fusionnées : *methode_classe_fusion*. Pour plus de détails, référez-vous à ?changement_COG_typo.


```{r, fig.show='hold'}
exemple_popcom_COG2017_typo <- changement_COG_typo(table_entree = exemple_popcom[,-2], annees = c(2014:2017),
                                                   methode_fusion = "methode_difference", typos = c("typoA","typoB"),
                                                   mot_difference = "differents", libgeo=TRUE,
                                                   donnees_insee=TRUE)
head(exemple_popcom_COG2017_typo)
```
La fonction `changement_COG_typo_details` permet quant à elle d'isoler dans une table les communes fusionnées appartenant à des classes différentes, ici selon la typologie "typoA" entre 2014 et 2015 puis 2015 et 2016 et 2016 et 2017. 

```{r, fig.show='hold'}
details_exemple_popcom_COG2017_typo <- changement_COG_typo_details(table_entree = exemple_popcom[,-2],
                                                                   annees = c(2014:2017), typo = "typoA",
                                                                   donnees_insee = TRUE)
head(details_exemple_popcom_COG2017_typo[["2014_2015"]])
head(details_exemple_popcom_COG2017_typo[["2015_2016"]])
head(details_exemple_popcom_COG2017_typo[["2016_2017"]])
```


## Agréger des tables de données communales à des échelons supra-communaux


La fonction `nivsupra` permet d'agréger les tables de données communales à de nombreux échelons supra-communaux administratifs (EPCI, arrondissements, cantons-villes, départements, régions) ou d'étude (bassins de vie, zones d'emploi, unités urbaines, aires urbaines) en indiquant le COG de la base de donnée en entrée et de référence des niveaux supra-communaux grâce au paramètre *COG* (par défaut vaut la valeur de `annee_ref`, la plus récente valeur contenue dans le package). Le paramètre *COG* peut prendre les valeurs 2008 à `annee_ref`.

Ici nous agrégeons la population et la superficie des communes à l'échelon géographique des zones d'emploi afin d'obtenir une table des densités de population par zone d'emploi.  

```{r, fig.show='hold'}
exemple_popcom_COG2017 <- merge(exemple_popcom_COG2017_num, exemple_popcom_COG2017_typo[,-2], by = "CODGEO",
                                all = TRUE)
exemple_popcom_ZE2010 <- nivsupra(table_entree = exemple_popcom_COG2017, nivsupra="ZE2010", agregation = TRUE,
                                  COG = 2017)
exemple_popcom_ZE2010$densite <- exemple_popcom_ZE2010$P12_POP / exemple_popcom_ZE2010$SUPERF
head(exemple_popcom_ZE2010)
```


## Gérer des cas particuliers dans les bases de données

### Enlever les arrondissements municipaux des tables de données communales

Nous allons maintenant manipuler une autre table exemple incluse dans le package, la table `exemple_flux` qui contient des exemples de flux entre une communes de résidences (COMMUNE) et de travail (DCLT). Elle contient comme autres variables le code de la catégorie socio-professionnelle des individus (CS1), la catégorie d'âge (AGEREVQ) et le poids de l'individu statistique (IPONDI). 

```{r, fig.show='hold'}
head(exemple_flux)
```

La fonction `enlever_PLM` permet de remplacer les codes Insee des arrondissements municipaux de Paris, Lyon et Marseille par leurs codes communes respectifs. 

Le paramètre *vecteur_entree* vaut TRUE si l'élément à transformer est un vecteur de codes insee et FALSE s'il s'agit d'une table de données (data.frame) numériques. Attention, cette fonction ne gère pas les conversions de typologies (variables de type caractère).

Ici nous allons remplacer les arrondissement municipaux par les codes communaux dans la table `exemple_flux` pour les variables COMMUNE puis DCLT.

```{r, fig.show='hold'}
exemple_flux_sansPLM <- enlever_PLM(table_entree = exemple_flux, codgeo_entree = "COMMUNE", libgeo = NULL,
                                    agregation = FALSE, vecteur_entree = FALSE)
exemple_flux_sansPLM <- enlever_PLM(table_entree = exemple_flux_sansPLM, codgeo_entree = "DCLT", libgeo = NULL,
                                    agregation = FALSE, vecteur_entree = FALSE)
```

###  Jongler avec les différentes possibilités pour les codes communaux corses

La fonction `modification_Corse` permet quant à elle de modifier les codes Insee des communes corses. En effet, en 1976, les codes de toutes les communes corses sont modifiés : alors qu'ils commençaient tous par "20", leurs deux premiers caractères sont remplacés par "2A" (Corse du Sud) ou "2B" (Corse du Nord). Les codes postaux conservent d'ailleurs aujourd'hui le préfixe historique "20". Cette fonction est notamment utile pour la raison suivante :  dans certaines tables issues des recensements Insee de 1968 ou 1975, les communes sont déjà codées avec les préfixes 2A et 2B. 

Le paramètre *sens* vaut "20vers2A2B" pour changer tous les codes communes corses commençant par 20 par 2A ou 2B et vaut "2A2Bvers20" quand l'effet inverse est recherché. 

```{r, fig.show='hold'}
exemple_flux_sansPLMsansCorse <- modification_Corse(table_entree = exemple_flux_sansPLM, sens = "2A2Bvers20")
```

### Corriger le code commune de l'Oudon dans le Calvados

La fonction `modification_Oudon` permet de modifier les codes Insee de l'ancienne commune de l'Oudon (Calvados, 14). Cette commune a connu une modification assez rare (transfert de chef-lieu) qui implique donc parfois des erreurs de codage de la commune dans certaines bases de données. En effet, la commune de l'Oudon a toujours été codée "14697" puis a changé de code devenant "14472" à partir du 07/01/2014 suite à un transfert de chef lieu. Cette commune a depuis disparu puisqu'elle est devenue commune déléguée au sein de Saint-Pierre-en-Auge (14654).

```{r, fig.show='hold'}
# Ici, nous allons remplacer les codes communes de l'Oudon dans une table de l'Insee
# (en COG 2014 mais que nous considérons en COG 2015 uniquement pour cet exemple).
head(exemple_popcom[which(exemple_popcom$CODGEO %in% c("14472","14697")),])
exemple_popcom_oudon <- modification_Oudon(table_entree = exemple_popcom,
                                           donnees_insee_entree = TRUE, donnees_insee_sortie = FALSE, COG = 2015)
head(exemple_popcom_oudon[which(exemple_popcom$CODGEO%in%c("14472","14697")),])
```


## Transformer des variables numériques en autre géographie dans des données de flux


La fonction `changement_COG_varNum` peut également s'appliquer à des tables de flux (codes communes pouvant comporter des doublons) grâce à l'option agregation = FALSE. Les variables de type caractère sont alors conservées comme telles ou dupliquées en cas de défusion et les variables numériques (ici IPONDI) sommées en cas de fusion ou réparties proportionnellement à la population de chaque commune en cas de défusion. 

```{r, fig.show='hold'}
exemple_flux_COG2017 <- changement_COG_varNum(table_entree = exemple_flux_sansPLMsansCorse,
                                              annees = c(2014:2017), codgeo_entree = "COMMUNE", agregation = FALSE,
                                              libgeo = FALSE, donnees_insee = TRUE)
exemple_flux_COG2017 <- changement_COG_varNum(table_entree = exemple_flux_COG2017,
                                              annees = c(2014:2017), codgeo_entree = "DCLT",
                                              agregation = FALSE, libgeo = FALSE, donnees_insee = TRUE)
```


## Insérer dans des tables de données de flux communales des échelons supra-communaux


La fonction `nivsupra` peut également s'appliquer à des tables de flux (non agrégées par codes communes) grâce à l'option agregation = FALSE. La table en entrée est alors conservée comme telle avec une nouvelle colonne qui correspond au niveau supracommunal du code commune considéré. 

Ici, on ajoute les colonnes ZE2010_COMMUNE et ZE2010_DCLT à la table de flux domicile-travail utilisée précédemment.

```{r, fig.show='hold'}
exemple_flux_COG2017_etZE <- nivsupra(table_entree = exemple_flux_COG2017, codgeo_entree = "COMMUNE",
                                      nivsupra = "ZE2010", agregation = FALSE, COG = 2017)
exemple_flux_COG2017_etZE <- nivsupra(table_entree = exemple_flux_COG2017_etZE, codgeo_entree = "DCLT",
                                      nivsupra = "ZE2010", agregation = FALSE, COG = 2017)
head(exemple_flux_COG2017_etZE)
```

Bonne découverte...!