COGugaison: Gestion des codes officiels géographiques (COG)

Documented in apparier_COG

#' @title Apparier une liste de communes avec un millésime de COG
#' @name apparier_COG
#' @description Comparer la liste des communes présente dans une table de données avec le COG d'un millésime donné. Fonction souvent utile après l'utilisation de la fonction COG_akinator.
#' @param vecteur_codgeo correspond à un vecteur de codes Insee communaux que l'on cherche à comparer au COG d'un millésime donné.
#' @param 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.
#' @param COG indique l'année de COG de la table considérée. (exemple 1968). Par défaut renvoie l'année retournée par la fonction COG_akinator
#' @return renvoie une liste composée de deux éléments :
#' \itemize{
#' \item{absent_de_bdd : un vecteur contenant l'ensemble des codes Insee présents dans le COG mais absents de la base de données.}
#' \item{absent_de_COG : un vecteur contenant l'ensemble des codes Insee présents dans la base de données mais absents du COG.}}
#' @details
#' Le code officiel géographique le plus récent du package est actuellement celui au 01/01/2023. \cr
#'
#' Les millésimes des COG qui peuvent être utilisés sont à ce stade les suivants : 1968, 1975, 1982, 1990, 1999, 2008 à 2023. \cr
#'
#' Les dates de référence des codes officiels géographiques utilisés dans COGugaison sont les suivantes :
#' \itemize{
#' \item{COG 1968 : à partir du 01/03/1968}
#' \item{COG 1975 : à partir du 20/02/1975}
#' \item{COG 1982 : à partir du 04/03/1982}
#' \item{COG 1990 : à partir du 05/03/1990}
#' \item{COG 1999 : à partir du 08/03/1999}
#' \item{Pour tous les autres COG : à partir du 01/01 de chaque année}} \cr
#'
#' Les différences entre les tables de passage Insee et non Insee sont les suivantes :\cr
#' \itemize{
#' \item{1982-03-03 (pris en compte par l'Insee seulement après le 04/03/1982): Flaignes-Havys (08169) est un rassemblement de Flaignes-Havys (08169), Havys (08221) [fusion simple].}
#' \item{2014-01-01 (pris en compte par l'Insee seulement au 01/01/2015) : Loisey (55298) s'est séparée en Loisey (55298), Culey (55138) [rétablissement].}
#' \item{1990-02-01 (pris en compte par l'Insee seulement après le 05/03/1990) : Le code commune de Oudon passe de 14624 à 14697 [changement de code dû à un changement de chef-lieu].}
#' \item{2014-01-07 (pris en compte par l'Insee  dès le 01/01/2016) : Tôtes est rattachée à Notre-Dame-de-Fresnay qui devient L'Oudon (changement de code de l'Oudon de 14697 à 14472) [transfert de chef-lieu].}
#' \item{1981-09-28 (pris en compte par l'Insee  dès le 20/02/1975) : Vaudreuil-Ex-Ensemble Urbain (27701) est créée à partir des parcelles d'Incarville (27351), de Léry (27365) , de Porte-Joie (27471) , de Poses  (27474) , de Saint-Étienne-du-Vauvray (27537), de Saint-Pierre-du-Vauvray (27598), de Tournedos-sur-Seine  (27651) et du Vaudreuil (27528) [création]. Cette situation étant complexe, nous avons pour le moment considéré que Vaudreuil-Ex-Ensemble Urbain (27701) est créée à partir de parcelles du Vaudreuil (27528) uniquement.}
#' \item{En 1968, les 4 communes qui auraient dû d'après le COG être codées 2B044,2B076,2B151 et 2A325 sont codées 20044,20076,20151 et 20325 dans les données Insee.}}
#' @references
#' \itemize{
#' \item{\href{https://www.insee.fr/fr/information/2666684#titre-bloc-11}{historique des géographies communales (Insee)}}
#' \item{\href{https://www.insee.fr/fr/information/2028028}{tables d'appartenance des communes aux différents niveaux géographiques (Insee)}}}
#' @seealso \link{changement_COG_varNum}, \link{changement_COG_typo},\link{changement_COG_typo_details}, \link{COG_akinator}, \link{enlever_PLM}, \link{modifications_communales},\link{nivsupra},\link{modification_Corse},\link{modification_Oudon},\link{trajectoire_commune}
#' @export
#' @examples
#' ## Exemple 1
#' 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)]
#' @encoding UTF-8


apparier_COG <- function(vecteur_codgeo, donnees_insee = TRUE,COG=as.numeric(substr(COG_akinator(vecteur_codgeo = vecteur_codgeo,donnees_insee = donnees_insee_entree),4,7))){
  # vérifier que COG est bien dans les annees_possibles
  if(!COG%in%annees_possibles){
    stop(paste0("COG doit être compris dans ",paste0(annees_possibles,collapse=", ")))
  }
  if(!is.vector(vecteur_codgeo)){
    stop("vecteur_codgeo doit être un vecteur.")

  }

 if(donnees_insee){
    assign(paste0("COG",COG),get(paste0("COG",COG,"_insee")))
  }

  vecteur_codgeo_COG <- get(paste0("COG", COG))[, 1]

  ### éléments qui sont dans le COG mais pas dans la base de données
  absent_de_bdd <- setdiff(vecteur_codgeo_COG,vecteur_codgeo)
  ### éléments qui sont dans la base de données et pas dans le COG
  absent_de_COG <- setdiff(vecteur_codgeo,vecteur_codgeo_COG)

  liste <- list(absent_de_bdd=absent_de_bdd, absent_de_COG=absent_de_COG)
  return(liste)

}