In andreoliant/octk: OpenCoesione Toolkit

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

Il toolkit contiene funzioni e processi per l'analisi dei dati pubblicati nella sezione open data del portale OpenCoesione.

Il workflow di base comprende i seguenti blocchi logici:

Importazione
Perimetrazione (query.R per l'estrazione multi-criteri e perimetro.R per la verifica e consolidamento)
Classificazione (classi.R per ...)
Esportazione (export.R per i dati per progetto e report.R per quelli aggregati)

E' disponibile l'utility per l'analisi delle variazioni tra bimestri di monitoraggio (delta.R).

Le funzioni assumono l'utilizzo delle denominazioni delle variabili in uso nel portale (vedi metadati)

I dati sono pubblicati qui.

Setup

Per l'utilizzo del toolkit è obbligatorio il seguente setup con 3 folder in locale.

Folder per dati OC

DATI/
  oc_20180630/
    progetti_esteso_20180630.csv
    ...

Folder per package OC

OC/
  R/
  man/
  dati/
  ...

Folder per workarea

WORK/
  main.R
  temp/
  input/
  output/

E' disponibile un wizard per il setup della workarea (crea automaticamente i folder input, output e temp) e la connessione ai dati (un prompt chiede di indicare il path e lo aggiunge al global environment). Se i paramentri di setup sono definiti nell'ambiente globale prima del caricamento del package vengono automaticamente utilizzati. Altrimenti intervengono le variabili di default del wizard. Il toolkit attualmente funziona solo in development mode. Per l'utilizzo è necessario il package R devtools.

# Parametri di setup
bimestre <- "20180630"         # Bimestre OC di riferimento
focus <- "turismo"             # Prefisso per i file da esportare
workarea <- "/path/to/project" # Path della workarea (es. progetto RStudio)
data_path <- "/path/to/data"   # Path dei dati 

# Library
# install.packages("devtools")
devtools::load_all(path = "/path/to/oc")

Per ottimizzare l'uso è bene definire anche i seguenti parametri che interessano esportazione e reportistica.

# Elenco delle variabili di OC (sono riportate nel file dati esteso)
var_ls <- c("COD_LOCALE_PROGETTO", "CUP", "OC_TITOLO_PROGETTO",
            "OC_COD_CICLO", "OC_COD_FONTE", "FONDO_COMUNITARIO",
            "CUP_COD_SETTORE",  "CUP_DESCR_SETTORE",  
            "CUP_COD_SOTTOSETTORE", "CUP_DESCR_SOTTOSETTORE", 
            "CUP_COD_CATEGORIA", "CUP_DESCR_CATEGORIA",
            "OC_DESCRIZIONE_PROGRAMMA", "OC_CODICE_PROGRAMMA",
            "OC_COD_ARTICOLAZ_PROGRAMMA", "OC_DESCR_ARTICOLAZ_PROGRAMMA", 
            "OC_COD_SUBARTICOLAZ_PROGRAMMA", "OC_DESCR_ARTICOLAZ_PROGRAMMA",
            "OC_FINANZ_TOT_PUB_NETTO", "IMPEGNI", "TOT_PAGAMENTI")

# Livelli di riferimento per la variabile CLASSE
livelli_classe <- c("Natura", "Cultura", "Turismo")

Importazione

Il workflow parte con l'importazione di progetti_esteso.csv. Il file va scaricato manualmente dal portale OpenCoesione e collocato nel folder DATI.

progetti <- load_progetti(bimestre = "20180630", visualizzati = TRUE, debug = TRUE)

Con il caricamento del package inoltre sono disponibili gli asset preparati dal Team di OpenCoesione:

matrix per facilitare il match tra i dati
supporti per le query sulle variabili
altri asset (es. riclassificazione)

In /data-raw ci sono gli asset originali (.csv) e lo script di conversione, mentre in /data ci sono le versioni in uso (.rda). Possono essere esportati per condivisione in oc_asset.xlsx.

Perimetro

L'identificazione del perimetro di progetti è effettuata con le funzioni di ricerca del blocco query_[CRITERIO]. E' possibile/raccomandato effettuare la ricerca secondo diversi criteri.

L'esecuzione di tali funzioni richiede l'esistenza corrispondenti file csv di input adeguatamente nominati e compilati. I template sono disponibili all'interno degli oc_asset e vanno esportati con la stessa denominazione nella cartella INPUT.

write.csv2(categorie_cup, file.path(INPUT, "categorie_cup.csv"), row.names = FALSE)
write.csv2(categorie_ue, file.path(INPUT, "categorie_ue.csv"), row.names = FALSE)
write.csv2(po_linee_azioni, file.path(INPUT, "po_linee_azioni.csv"), row.names = FALSE)

La variabile QUERY del template va compilata con i seguenti valori:

0 per gli item non pertinenti
1 per gli item sicuramente pertinenti
2 per gli item da valutare a valle in base all'effettivo contenuto dei record

Ogni funzione applica il criterio di ricerca al dataset progetti e restuisce l'elenco dei CLP e la variabile QUERY.

peri_cup <- query_cup(progetti)
peri_po <- query_po(progetti)
peri_ue <- query_ue(progetti)

Il file pseudo.csv è obbligatorio perché costituisce l'ossatura dell'intero workflow e non solo della sezione relativa alla ricerca. Va creato mediante full_join dei risultati di ricerca e salvato in TEMP. Il file contiene almeno l'elenco dei CLP e i valori di QUERY in corrispondenza di ciascun criterio di ricerca.

E' anche disponibile un wrapper per aggregare i diversi processi di ricerca. Per ogni funzione di ricerca richiesta il wrapper integra il file pseudo.csv.

# creazione manuale di pseudo:
pseudo <- peri_cup %>%
    full_join(peri_po) %>%
    full_join(peri_ue)
write.csv2(pseudo, file.path(TEMP, "pseudo.csv"), row.names = FALSE)

# creazione di pseudo con il wrapper standard:
pseudo <- make_pseudo_std(progetti, export=TRUE)
# MEMO: usa le 3 query

# creazione di pseudo con il wrapper editabile:
pseudo <- make_pseudo_edit(progetti, query_ls=c("query_cup", "query_po"), export=TRUE)
# MEMO: seleziona le query desiderate

# ricarica pseudo (ad es. in una nuova sessione)
pseudo <- read_csv2(file.path(TEMP, "pseudo.csv"))

E' possibile anche integrare pseudo con righe provenienti da funzioni specifiche create per analisi ricorrenti.

# Integrazione progetti turismo da precedente metodologia
pseudo <- add_old_turismo(pseudo, export=TRUE)

Il processo di ricerca è finalizzato con lo scarto dei progetti individuati esclusivamente tramite un criterio dubbio e l'applicazione di rettifiche individuali per:

salvare il progetto che sarebbe stato eliminato dal perimeto (se inserito in safelist.csv)
eliminare un progetto che sarebbe rimasto nel perimeto (se inserito in stoplist.csv)

I template sono disponibili all'interno degli oc_asset e vanno esportati con la stessa denominazione nella cartella INPUT. Le righe di esempio descrivono le regole di compilazione.

write.csv2(stoplist, file.path(INPUT, "stoplist.csv"), row.names = FALSE)
write.csv2(safelist, file.path(INPUT, "safelist.csv"), row.names = FALSE)

Una volta popolate stoplist e safelist si integra pseudo con la definizione del perimetro.

pseudo <- make_perimetro(pseudo, export=TRUE, debug=TRUE)
# DEV: qui va fatto anche blocco per query editabili

Controllo dei risultati

L'esito del processo è visionabile nel file scarti_perim.csv e mediante gli strumenti dedicati disponibli in analisi.R per l'esecuzione line-by-line. A valle dei controlli è possibile ritornare indietro nel workflow per:

ridefinire i criteri nel blocco query (ad es. con il passaggio da "2" a "0" di voci rivelatesi sistematicamente erronee)
integrare gli elenchi in safelist.csv e stoplist.csv

Altrimenti si può procedere alla classificazione (se prevista) oppure all'esportazione.

Classificazione

E' disponibile in beta il processo di classificazione in ambiti di secondo livello rispetto al focus del perimetro. Anche questa funzione si appoggia sulla struttura di pseudo.csv e puo essere utilizzata interattivamete per correzioni puntuali mediante fixlist.csv.

pseudo <- make_classi(pseudo,
                      classe_jolly="Turismo",
                      livelli_classe = c("Natura", "Cultura", "Turismo"),
                      export=TRUE, debug=FALSE)

Esportazione

Il processo di esportazione salva il dataset con il perimetro individuato.

perimetro <- export_data(pseudo, focus, bimestre, var_ls, var_add=NULL, chk_today="20180731")

Inoltre è possibile esportate la reportistica sintetica.

export_report(perimetro, use_template=TRUE)

Analisi variazioni

Il processo può essere replicato per ogni bimestre di monitoraggio. Per ridurre l'effort dedicato ad analisi manuali è possibile utilizzare l'utility dedicat all'analisi delle variazioni tra bimestri di monitoraggio, che isola solo il nuovo delta di progetti non censiti né scartati nel precedente esercizio.

delta <- make_delta(perimetro, path_to_old = OLD, debug=TRUE)
# chk_match(perimetro, delta, id="COD_LOCALE_PROGETTO")
# chk_match(perimetro, perim_old, id="COD_LOCALE_PROGETTO")
chk_delta(perimetro, path_to_old = OLD, debug=TRUE)
make_delta_scarti(pseudo, perimetro, path_to_old = OLD, debug=TRUE, var_ls, min_cp=2000000)