Parametri utente

Spesso è utile parametrizzare il comportamento di uno script, per esempio nel caso di indagini continuative, per generare i nomi dei file con i riferimenti della fase o per selezionare i dati del corretto intervallo temporale, oppure quando si vuole realizzare diversi report ciascuno con un pannello differente, report ponderati e non, ecc.

pTabs2 dispone di vari metodi che permettono all’utente di variare i parametri passati allo script. I parametri possono essere posti semplicemente in cima allo script così da poter essere modificati facilmente, possono essere richiesti all’utente, oppure essere in file esterni allo script. Ciascun metodo può essere più o meno adatto in relazione allo specifico caso.

Variabili $x1, $x2, $x3, $x4, ...

All’interno dello script è possibile utilizzare le variabili $x1, $x2, $x3, $x4, ecc. che, al momento dell’esecuzione, verranno sostituite con i corrispondenti parametri.

1
spss.open "data_#{$x1}W#{$x2}"

Nel caso non vengano forniti i valore dei parametri, è possibile preimpostare dei valori di default nello script con la sintassi:

1
$x1 ||= valore

I parametri possono essere passati allo script eseguendolo tramite la linea di comando, all’interno di un batch file o direttamente in SciTE.

1) linea di comando

In una finestra della console di Windows, digitare ptabs2, il nome dello script e la lista dei parametri:

C:\my\folder>ptabs2 script_name.pt2 param1 param2 ...

I parametri sono semplicemente separati da uno spazio (non da virgole). Il primo parametro corrisponderà alla variabile $x1, il secondo a $x2 e così via.

2) batch file

Creare un file con estensione .bat per eseguire uno o più script di pTabs. Ciascuna linea di comando all’interno del batch file deve essere costituita da:

call ptabs2 script_name.pt2 param1 param2 ...

I parametri sono semplicemente separati da uno spazio (non da virgole). Il primo parametro corrisponderà alla variabile $x1, il secondo a $x2 e così via.

Il batch file può essere successivamente eseguito da linea di comando oppure aperto in SciTE ed eseguito con F5.

esempio.bat:

rem Pannello 1
call ptabs2 tavole.pt2 p1 p
call ptabs2 tavole.pt2 p1 np

rem Pannello 2
call ptabs2 tavole.pt2 p2 p
call ptabs2 tavole.pt2 p2 np

3) SciTE

In SciTE, dopo aver aperto uno script di pTabs2, premendo Shift-F8 (Maiusc-F8) si aprire una finestra di dialogo che permette l’inserimento dei parametri.

_images/scite_parameters.png

Chiudendo la maschera con Set i parametri verranno memorizzati e si potrà eseguire lo script. Il pulsante F5 è comunque disponibile anche con la maschera aperta; in questo modo è possibile cambiare i parametri e immediatamente eseguire lo script.

  • I parametri devono essere inseriti senza utilizzare spazi, altrimenti ogni spazio determina la creazione di un nuovo parametro (anche oltre il quarto). Si può sfruttare questa caratterisitca per creare più di quattro parametri.
  • Per etichette e testi contenenti spazi utilizzare le virgolette.
  • Lasciando un parametro vuoto, il successivo prenderà il posto del precedente.
_images/scite_parameters2.png

ask

ask genera una finestra di dialogo con i pulsanti indicati oltre al pulsante Stop script. Restituisce il codice associato al pulsante.

I pulsanti devono essere indicati tramite un Hash con le coppie codice/etichetta (default 1 => "Yes", 2 => "No").

Argomenti:

  • question: il testo della finestra
  • {}||[]: un hash con le due coppie codice => etichetta per i pulsanti o un array di valori, in tal caso il codice sarà uguale all’etichetta
1
filter :user => 1 if ask("Devo selezionare solo gli utenti?")
_images/ask1.png 
1
ask("Seleziona il sample", (1..7).to_a)
_images/ask2.png 
1
ask!("Quale paese vuoi selezionare?", {1 => "Italia", 2 => "Spagna", 3 => "Francia", 4 => "Germania", 5 => "Portogallo" })
_images/ask3.png

input

input genera una finestra di dialogo per l’inserimento di un parametro da parte dell’utente. Se non viene specificato :to_vector o :to_i, il parametro inserito viene restituito come stringa.

Argomenti:

  • question: il testo della finestra
  • :default => value: il valore di default
  • :to_vector => true|false: true genera un vettore separando la stringa di dati inseriti in base alle virgole (default false)
  • :to_i => true|false: true converte i dati inseriti in numero intero (default false)
1
2
filename = input("Digitare il nome del file con i dati da elaborare")
xlsx.open filename
_images/input.png

Consiglio

E’ possibile porre ask e input all’inizio dello script salvando i risultati in variabili da usare più avanti, in modo da inserire tutti i parametri all’inizio dell’esecuzione.

setup

setup è un oggetto utile per memorizzare in modo ordinato parametri di configurazione.
E’ possibile definire uno o più namespace (per esempio il nome sintetico dell’indagine) e, al suo interno, i parametri desiderati.
E’ possibile utilizzare la sintassi a blocco per definire più parametri oppure definirli singolarmente. Il nome definito nel blocco è arbitrario e ha validità solo all’interno del blocco.
I parametri possono anche essere modificati semplicemente ridefinendoli.

In seguito è possibile richiamare i parametri ovunque nello script con la sintassi setup.namespace.param.
Se invece si richiama un parametro con un punto esclamativo alla fine del nome (setup.namespace.param!), nel caso il parametro non sia stato definito, verrà generato un errore.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
setup.abc do |x|
  x.param1 = 1
  x.param2 = "due"
  x.attrib3 = :tre
  x.yz.param1 = "A"
end

setup.ST.param1 = "uno"
setup.abc.attrib4 = 4
setup.abc.yz.param2 = "B"

setup.abc.param1     # => 1
setup.abc.param2     # => "due"
setup.abc.attrib3    # => :tre
setup.abc.attrib4    # => 4
setup.abc.yz.param1  # => "A"
setup.abc.yz.param2  # => "B"
setup.ST.param1      # => "uno"

Esempio

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
setup.myx do |x|
  x.year     = 2021
  x.month    = 5
  x.datafile = "p6847685472_abc.xyz_4236519_responseid"
  x.type     = :prospect
end

setup.myx do |x|
  x.name     = x.year.to_s + "W" + x.month.to_s.rjust(2, "0")     # => "2021W05"
  x.wave     = x.year * 100 + x.month                             # => 202105
end

setup.myx.openfile = "Codifica_#{setup.myx.name}"                 # => "Codifica_2021W05"
setup.myx.path     = "data/#{setup.myx.wave}/#{setup.myx.type}"   # => "data/202105/prospect"

name "report_#{setup.myx.name}"                                   # => "report_2021W05"
spss.open "#{setup.myx.path}/#{setup.myx.datafile}.sav"           # => "data/202105/prospect/p6847685472_abc.xyz_4236519_responseid.sav"

Normalmente setup viene definito all’inizio dello script, in modo che appaia subito chiaro quali siano i parametri da modificare, oppure in un file esterno che viene incluso con inc{}, in questo modo si potranno riutilizzare gli stessi parametri in più script senza doverli ripetere.

Metodi:

  • has_key?(:param_name): restituisce true se il parametro è stato definito altrimenti false
  • clear!: elimina i parametri definiti
  • save!(name): scrive nella cartella di lavoro un file nmae.setup.yaml con i parametri definiti. Può essere utilizzato, per esempio:
    • per impostare solo nel primo script parametri da usare in una serie di script successivi
    • per passare dati generati all’interno di uno script a un altro script

*.setup.yaml

All’avvio, pTabs2 popola l’oggetto setup con i parametri trovati nei file con il nome che finisce per .setup.yaml se presenti, cercandoli nelle seguenti cartelle:

  • nelle cartelle genitori della cartella di lavoro
  • nella cartella di lavoro

*.setup.xlsx

E’ anche possibile popolare l’oggetto setup attraverso un file XLSX.
All’avvio, pTabs2 cerca tutti i file XLSX con il nome che finisce per .setup.xlsx nelle seguenti cartelle:

  • cartelle genitori della cartella di lavoro
  • cartella di lavoro

I file possono contenere uno o più fogli. Ciascun foglio deve contenere due colonne intestate come param e value. Il contenuto dei file andrà a popolare l’oggetto setup, il nome di ciascun foglio definisce il namespace. Tutti i file trovati contribuiranno a popolare l’oggetto setup eventualmente sovrascrivendo gli stessi parametri se presenti in più file. Non è possibile utilizzare valori calcolati. L’oggetto setup può essere ulteriormente modificato nello script.

_images/config_xlsx.png 
1
2
3
4
5
6
setup.pro.year      # => 2022
setup.pro.month     # => 5
setup.pro.datafile  # => "p6847685472_abc.xyz_4236519_responseid"
setup.pro.type      # => :prospect

setup.cli.type      # => :client