3. Progettazione e sviluppo di Arpus
3.5 Struttura del Software
config.php
Il file contiene le funzioni che si occupano di aprire e chiudere la connessione al database, inserire modificare stringhe e prepararle all’inserimento nella base di dati e interrogazione.
Le funzioni contenute sono le seguenti:
• OpenDB() : apre la connessione al database. • CloseDB(): chiude la connessione al database.
• escapeString($str): prende una stringa come parametro e restituisce un’altra stringa su cui è stata chiamata la funzione mysqli_real_escape_string(), che la prepara per l’inserimento nel database.
• insert($sql): prende una stringa contenente la query da sottoporre al database, non stampa alcun risultato (utilizzata per modifiche al database).
• queryDB($sql): prende una stringa contenente la query da sottoporre al database, restituendo una variabile contenente i risultati della query.
Home.php
File php contenente il codice HTML della pagina principale e in cui vengono creati dinamicamente grafici e tabelle e campi contenenti le informazioni del docente.
Il file contiene script e link della libreria jQuery [32] DataTables [33] utilizzata per la creazione di tabelle con varie funzionalità, tra cui esportazione, stampa della tabella, selezione dei campi e ricerca.
Un’altra libreria, ApexCharts[34] è stata utilizzata per la creazione dei grafici contenenti il numero e la tipologia di pubblicazioni del docente. Sono presenti infatti un grafico a
colonne con il numero di pubblicazioni nel corso degli anni e un grafico a torta che riporta il numero di pubblicazioni di un docente per ciascun tipo.
Index.php
File contenente la classe manager(), il cui costruttore prende come parametro l’id del docente che si vuole cercare e inizializza le variabili $data, $PrimaFascia, $SecondaFascia, rispettivamente con la data odierna e le istanze di CalcoloIndicatori per la prima e la seconda fascia, che si differenziano per il numero di anni in cui vengono calcolati gli indicatori ASN e che a loro volta prevedono come parametro il numero di anni, l’id del docente e la data.
Gli indicatori, calcolati in precedenza, sia per le pubblicazioni su Scopus che per quelle su ARPI, vengono estratti dal database (tabella indicatori) e immagazzinati all’interno delle relative variabili.
La classe manager è composta dai seguenti metodi:
• ottieniSoglie():
Il metodo prende come parametro un settore ($set) e permette di inizializzare le variabili per articoli, citazioni e indice h per le tre fasce già sopracitate, con gli indicatori calcolati con le pubblicazioni ottenute da Scopus e da Arpi.
Le variabili sono le seguenti:
• il numero di articoli del docente per commissari, prima e seconda fascia ($artFC, $artF, $artF2, $artFCArpi, $artF1Arpi e $artF2Arpi);
• il numero di citazioni della produzione scientifica del docente presentata nella domanda ($citFC, $citF1, $citF2, $citFCArpi, $citF1Arpi e $citF2Arpi);
• l’indice h del docente ($HFC, $HF1, $HF2, HFCArpi, $HF1Arpi e $HF2Arpi); • Il numero totale di articoli del docente ($totA);
• L’indice h del docente calcolato su tutta la carriera ($totH);
• Il numero di pubblicazioni che rientrano nell’arco di tempo della seconda per i commissari ($pubDomandaFC);
• Il numero di pubblicazioni che rientrano nell’arco di tempo della prima fascia ($pubDomandaF1);
• Il numero di pubblicazioni che rientrano nell’arco di tempo della seconda fascia ($pubDomandaF2);
• Il numero medio di autori per la fascia per commissari ($autoriFC); • Il numero medio di autori per la prima fascia ($autoriF1);
• Il numero medio di autori per la seconda fascia ($autoriF2);
• Il risultato del metodo settori() dell’istanza PrimaFascia che prende come parametro $set, il settore preso a sua volta come parametro dalla classe
manager ($strSettori);
• Un array contenente le soglie per il settore del docente ottenuto invocando il metodo soglie dell’istanza PrimaFascia, passando come parametro la variabile
$set, $autoriF1, autoriF2 e $autoriFC ($soglie);
Se la variabile $soglie risulta essere uguale a true, viene creata una variabile $toPrint contenente il codice HTML per la tabella con gli indicatori e le relative soglie per il settore $set.
Se $set è uguale al settore FIS/01 e il numero complessivo di articoli per il concorso per la prima fascia è uguale a 0, la variabile $toPrint riporta un messaggio in cui viene spiegato che non è stato possibile ottenere i dati da Scopus tramite un processo di download automatizzato per tutti i docenti del settore a causa del numero troppo elevato di co-autori di alcune pubblicazioni.
Pertanto viene identificato il docente come “senza dati” ($this→docenteSenzaDati =
Se la variabile $soglie risulta essere uguale a false significa che non sono state trovate soglie per quel settore, la variabile $toPrint viene inizializzata come vuota e il settore preso in analisi viene riconosciuto come non bibliometrico ($this→bibliometrico=
false).
Se il docente risulta avere tutti i dati, una volta individuate le relative soglie e ottenuto il numero di articoli, citazioni e l’indice-H, viene “costruita” la tabella contenente gli indicatori ASN, all’interno di $toPrint.
Il metodo restituisce infine la variabile $toPrint come risultato.
• Profile():
Il metodo interroga la base di dati contenente la tabella docente e va a ricavare le informazioni necessarie (nome, cognome, ruolo, settore) dalla tabella docenti in base all’id del docente passato alla classe manager.
Se il risultato non è pari a zero, ovvero se il docente con quell’identificativo
Scopus esiste, vengono calcolate le pubblicazioni Q1, invocando il metodo quartileCount(), dell’istanza primaFascia() e allo stesso modo viene utilizzato il
metodo countPubs() per calcolare il numero di pubblicazioni del docente.
Alla variabile $settore viene attribuito il valore dell’attributo settore, risultate dall’interrogazione al database.
Viene inoltre creata una variabile $setSub, contenente una sotto-stringa di $settore, in maniera tale che sia confrontabile con il campo contenuto nella tabella soglie.
In seguito viene creata una variabile $toPrint, che sarà restituita come risultato del metodo, contenente la tabella con il ruolo, settore, numero di pubblicazioni,
numero di pubblicazioni Q1. Alla variabile viene in seguito aggiunto il risultato
di ottieniSoglie($setSub);
Se l’identificativo inserito non esiste o non corrisponde a quello di alcun docente dell’Università di Pisa, la variabile $toPrint assume il valore di una stringa che avvisa l’utente, che l’id inserito non corrisponde a nessun docente Unipi.
Il metodo inoltre controlla se il docente ha dato o meno il consenso per il trattamento dei propri dati, in caso positivo viene data la possibilità di revoca, altrimenti viene mostrato un link ad una finestra pop-up che permette di fornire l’autorizzazione al trattamento e alla visualizzazione dei propri dati all’interno della pagina MEDIANE.
• divGrafici():
Il metodo crea i blocchi HTML <div>, che andranno a contenere i grafici del docente all’interno della variabile $html. Essi vengono creati solamente nel caso in cui il docente non sia classificato come “senza dati” ($this ->
DocenteSenzaDati == false). In caso contrario la variabile verrà restituita vuota.
• tabellaSoglie():
Controlla che l’id del docente passato alla classe esista all’interno della tabella
dei docenti, in caso positivo preleva nome, cognome, ruolo e settore di questo, modifica la stringa del settore e invoca, passando quest’ultimo come parametro, il metodo ottieniSoglie().
• pubblicazioniDocente():
Metodo che restituisce le pubblicazioni del docente in una tabella.
• selectSelettore():
ottiene tramite metodo get e immagazzina dentro $query il valore del settore selezionato dall’utente nella tabella degli indicatori ASN e lo passa al metodo
ottieniSoglie().
Ciò è stato fatto in maniera che l’utente possa visualizzare dinamicamente le soglie per altri settori.
• notifiche():
Controlla se il docente abbia attivato o meno il servizio di notifica tramite e- mail. In caso positivo crea una finestra HTML con un pulsante che permette di disattivare il servizio di aggiornamento, altrimenti la finestra creata permette di attivarlo. In entrambi i casi viene registrata l’azione dell’utente e aggiornato il database.
• Trattamento():
Il metodo rileva se il docente abbia dato o meno il consenso al trattamento dei dati, in caso positivo crea una finestra html con un pulsante che permette di revocare il consenso e impedire la visualizzazione dei propri dati, altrimenti viene data la possibilità all’utente di acconsentire. Anche in questo caso viene aggiornato il database in tempo reale, con la revoca o l’accettazione da parte del docente.
Indicatori.php
Il file contiene la classe CalcoloIndicatori(), il costruttore prende come parametri l’identificativo del docente, la data odierna e la fascia di anni in cui vengono calcolati i tre indicatori ASN (articoli, citazioni, indice h) sia in base alle pubblicazioni di Scopus che su quelle di ARPI. Queste vengono immagazzinate nelle variabili $citationscount
,$articlecount , $hindex , $articleArpi, $citationsArpi , $hindexArpi.
La classe è composta da i seguenti metodi:
• settori():
Il metodo è utilizzato per la visualizzazione degli altri settori nel menù a discesa, della tabella degli indicatori ASN.
Il primo settore restituito è quello del docente, nella seconda query vengono ricavati gli altri settori e aggiunti alla variabile $dropdown, contenente il codice html del menù e infine restituita dal metodo.
• soglie($s, $autF1, $autF2, $autFC):
Il metodo prende quattro parametri: un settore scientifico disciplinare, che nel caso dell’applicazione viene passato dall’istanza di manager, il numero medio di autori considerando le pubblicazioni valide nell’arco di tempo stabilito per la fascia per commissari. prima e seconda fascia.
Viene creata una query che interroga il database per cercare il settore scientifico disciplinare del docente, questo viene quindi salvato in una variabile denominata
$settore.
Il metodo crea un variabile $set che assume il valore di una sotto-stringa di
$settore.
Il numero medio di autori viene utilizzato in particolare per il settore scientifico disciplinare FIS/01, per il quale sono previste soglie diverse in base al numero di coautori.
Nello specifico le mediane si differenziano in base ad un numero di coautori minore uguale di 500, tra 501 e 1200 (compresi) e maggiore uguale di 1201. Una volta individuato il caso specifico dell’autore viene quindi selezionato, tramite query SQL, il record giusto per la prima e seconda fascia; se il settore non corrisponde a FIS/01, il metodo cerca nella tabella soglie il settore che corrisponde al parametro passato. Nel caso in cui trovi una corrispondenza le soglie individuate vengono salvate nelle corrispettive variabili, altrimenti viene cercato il settore corrispondente alla variabile $set
In ogni caso le soglie vengono inserite in un array e restituite dal metodo. Nel caso in cui non vengano trovate soglie il metodo restituisce false.
• numeroAutori():
Calcola e immagina all’interno della variabile $this→ autori, il numero complessivo di co-autori nella produzione scientifica dell’autore, considerando l’arco di tempo passato come parametro alla classe e quindi la relativa fascia.
• totcitations():
Calcola e restituisce il numero totale di citazioni per il docente selezionato.
• totarticles():
Calcola e restituisce il numero totale di articoli per il docente selezionato.
• totHindex():
Calcola e restituisce l’h-index su tutta la carriera del docente selezionato.
• citations():
Calcola il numero di citazioni nel periodo di tempo definito nella varibile $cit.
• articles():
Calcola il numero di citazioni nel periodo di tempo definito nella variabile $art.
• Hindex():
Calcola l’indice h dell’autore, nel periodo di tempo definito nella variabile $hi. l'H-index è una misura che cerca di coniugare numerosità ed impatto della produzione scientifica.
È stato proposto dal fisico Jorge E.Hirsch nel 2005.
Definizione: un ricercatore/docente ha h-index pari a N se ha pubblicato almeno
N lavori citati almeno N volte ciascuno.
Come si misura? Posto che abbiamo a disposizione la lista degli articoli con ciascuno, il numero di citazioni ottenute, si dispongono in ordine decrescente per numero di citazioni; N sarà la posizione tale per cui alla posizione N+1 il numero di citazioni è inferiore a N+1 [14].
• articlesArpi():
Metodo che preleva la matricola corrispondente all’id del docente passato dalla tabella dei docenti, in modo tale da poter calcolare il numero di articoli per la domanda solamente tra quelli di Arpi (tabella handle) e immagazzinare il risultato nella variabile $this → articleArpi.
• citationsArpi():
Conta il numero di citazioni all’interno delle pubblicazioni rilevate su Arpi e le registra all’interno della variabile $this → citationsArpi
• HindexArpi():
Indice-h calcolato in base alle pubblicazioni su Arpi.
• Quartilecount():
Il metodo conta tramite query SQL e restituisce, il numero di pubblicazioni Q1 dalla tabella Quartile unita con una JOIN alla tabella pubb.
• Pub():
Il metodo restituisce le pubblicazioni dell’autore cercato e le relative informazioni (titolo, data, autori, tipo di pubblicazione, issn, quartile, numero di citazioni) in una tabella.
Controlla inoltre se l’autore abbia dato o meno il consenso per l’attivazione del servizio di aggiornamento, mostrando un link ad una finestra pop-up diverso in base al risultato.
• countPubs():
Il metodo conta tramite query SQL e restituisce, il numero totale di pubblicazioni dalla tabella pubb per il docente selezionato.
dataChart.php e pieChart.php
Due file php che estraggono i dati dal database, necessari per la creazione rispettivamente di un grafico a colonne e di uno a torta nella pagina HOME, restituendo i dati serializzati in formato JSON e con la struttura adeguata, richiesta dalla libreria
ApexCharts, che varia a seconda del grafico desiderato.
dipartimentoChart.php
File che si occupa dell’estrazione dei dati dal database per la creazione del grafico all’interno della pagina AGGREGATI, che mostra la percentuale dei docenti che superano le soglie per la fascia successiva alla propria, in base al settore selezionato.
graficoDipartimenti.php
Serve per l’estrazione dal database dei dati necessari alla creazione dei vari grafici creati a seconda del dipartimento che riportano il numero di docenti in base al ruolo che superano le soglie per la fascia superiore.
importCsv.php
Il file contiene le seguenti funzioni:
• docenti():
La funzione prende come parametro la variabile $tab in cui è immagazzinato il nome della tabella docenti scelta; se l’utente vuole utilizzare Arpus con un sottoinsieme di docenti , $tab assume il valore di sottoinsieme, in modo tale da poter importare i dati all’interno dell’omonima tabella, viceversa se l’utente intende utilizzare il database completo viene assegnato a $tab il valore docenti, così da poter importare con la stessa funzione i dati all’interno di un’altra tabella (quella completa).
La funzione quindi si occupa di estrarre e mappare i dati contenuti nel file CSV
• arpi():
Funzione che si occupa di importare all’interno della tabella handle i dati all’interno del file CSV. Viene inoltre modificata la matricola di ciascun docente, affinché risulti di almeno 6 caratteri, aggiungendo gli “0” mancanti. Infine viene registrata la data di aggiornamento della tabella, che viene mostrata anche nella pagina AGGREGATI.
login.php, logout.php, verifica.php
File creati per l’accesso tramite credenziali ad Arpus (login.php) di cui viene controllata la correttezza e l’esistenza e i permessi attribuiti all’utente (all’interno di verifica.php).
getPub.php
Contenente le seguenti funzioni:
• getPub():
Scarica e inserisce nella tabella Pubb, le pubblicazioni di tutti i docenti dell’Università di Pisa, utilizzando il matching service con gli id estratti dalla tabella Docenti.
• update():
Scarica le pubblicazioni tramite la funzione getPub() e le confronta con quelle già presenti nel database; cancella quelle più vecchie e se ce ne sono di nuove ne stampa l’eid. Nel caso in cui il database fosse già stato aggiornato lo stesso giorno, non vengono scaricate di nuovo le pubblicazioni, ma viene visualizzato il messaggio “database già aggiornato”.
La funzione inoltre cerca all’interno dei docenti quelli che hanno attivato il servizio di aggiornamento tramite e-mail e quali di essi possiedono pubblicazioni aggiunte alla tabella pubb durante l’ultimo aggiornamento. Una
volta individuati, viene invocata la funzione inviaEmail($destinatario,
$pubblicazioni);
questa vuole ciascun docente e le sue pubblicazioni “nuove”, come parametro e invia un’e-mail contenente l’elenco delle pubblicazioni e relativi dati (eid,issn,rivista).
All’interno della funzione, infine, vengono invocate nel seguente ordine le funzioni: issnUpdate(), aggiornaIndicatori() e soglieSuperate(), affinchè sia completato l’aggiornamento del database sotto ogni punto di vista.
• issnUpdate() e issnUpdateScimago():
Funzioni che interrogano il database cercando gli attributi issn1 e issn2 della tabella pubb, e di scimago; se il numero di record ottenuti è pari a zero, allora vengono creati i relativi campi issn1 e issn2.
Viene fatto un controllo nella tabella scimago, eliminando i record il cui attributo Quartile è diverso da Q1, poiché non necessari.
Sia per la tabella Scimago che per pubb, viene preso per ciascun record l’attributo contenente l’issn, e suddiviso in due parti, issn1 e issn2, utilizzando a funzioni e PHP explode() che prende come parametro una stringa e un “separatore” che divide i pezzi della stringa che saranno separati e inseriti in un array. Una volta create e riempiti i due campi in entrambe le tabelle, tramite query SQL viene creata (prima eliminata se già esistente), la tabella Quartile, la quale viene riempita con il risultato di quattro JOIN SQL unite, tra la tabella
Scimago e pubb, in cui vengono cercate le pubblicazioni classificate come Q1
presenti sia in Scimago che in pubb.
Così facendo si ottiene una tabella con tutte le pubblicazioni qualificate come
Best Quartile, pubblicate dai docenti dell’Università di Pisa, utile a velocizzare
il conteggio delle pubblicazioni Q1, visualizzato nelle singole pagine dei docenti.
• inviaEmail($destinatario,$pubblicazioni):
Prende come parametro un destinatario e un insieme di pubblicazioni ($pubblicazioni), passate sotto forma di stringa, contenente il codice HTML per la creazione di una tabella all’interno dell’e-mail da inviare al destinatario.