Funzioni di utilità

s

s o seq genera una lista di nomi di variabili. Il carattere # [1], se presente, viene sostituito dal numero della sequenza. E’ possibile utilizzare interi (10), range (2..7), vettori (1,3,5,7,9). Un numero negativo esclude l’elemento dalla sequenza. Eventuali elementi non numerici ('net_2') vengono inseriti come sono. Se tutti gli elementi sono stringhe, verranno sostituiti al carattere #. Specificando solo la radice del nome, vengono restituiti i nomi di variabili presenti nel file di dati che iniziano con quei caratteri. Un numero negativo esclude l’elemento dalla sequenza. true come secondo argomento, esegue il padding con lo zero in base al numero di cifre del numero più alto della sequenza.

 s(string, sequences/ranges/values/names)
 s(string, padding, sequences/ranges/values/names)
 s([pre,post], padding, sequences/ranges/values/names)

 s(:x_, 1,2,3,4,5)                    # => [:x_1, :x_2, :x_3, :x_4, :x_5]
 s(:d2_1_,1..4)                       # => [:d2_1_1, :d2_1_2, :d2_1_3, :d2_1_4] (numero sequenza in fondo)
 s("d2_#_1",1..4)                     # => [:d2_1_1, :d2_2_1, :d2_3_1, :d2_4_1] (numero sequenza interno)
 s(:x_,99,98,7..10,1..3)              # => [:x_99, :x_98, :x_7, :x_8, :x_9, :x_10, :x_1, :x_2, :x_3]
 s(:x_, true, 7..10)                  # => [:x_07, :x_08, :x_09, :x_10]
 s(:x1_, 1..7,-4,-6)                  # => [:x1_1, :x1_2, :x1_3, :x1_5, :x1_7]
 s(:q, 1..7,-6..-4)                   # => [:q1, :q2, :q3, :q7]
 s(:x, 1..3,:net1,4..7,'net_2',99)    # => [:x1, :x2, :x3, :net1, :x4, :x5, :x6,: x7, :net_2 :x99]
 s("x#", ["1","2","3a","3b","4"])     # => [:x1, :x2, :x3a, :x3b, :x4]
 s([:v,'_1'], 101..104,199)           # => [:v101_1, :v102_1, :v103_1, :v104_1, :v199_1]
 s('v#_1', 101..104,199)              # => [:v101_1, :v102_1, :v103_1, :v104_1, :v199_1]

 s(:v10_)                             # => ricerca automatica delle variabili nel file di dati
 s(:v10_,:a)                          # => ricerca automatica con ordinamento alfabetico

s permette anche di generare sequenze numeriche.

 s(5)         # => [1,2,3,4,5]
 s(3..9)      # => [3,4,5,6,7,8,9]

s2

Come s, ma quando si utilizza un solo numero intero non lo interpreta come il limite superiore della serie che parte da 1, ma come singolo codice.

 s2(:x_, 3)     # => ["x_3"]
 s(:x_, 3)      # => ["x_1", "x_2", "x_3"]

s0, s00, s000, s0000

Come s, ma aggiunge il padding con lo zero (rispettivamente a 2, 3, 4 e 5 cifre) indipendentemente dal numero di cifre presenti nei numeri della sequenza.

 s0(:d1_, 5..9)                  # => ["d1_05", "d1_06", "d1_07", "d1_08", "d1_09"]
 s0(:d1_, 5..10)                 # => ["d1_05", "d1_06", "d1_07", "d1_08", "d1_09", "d1_10"]
 s00(:d1_, 97..101)              # => ["d1_097", "d1_098", "d1_099", "d1_100", "d1_101"]
 s000(:d1_, 97..101)             # => ["d1_0097", "d1_0098", "d1_0099", "d1_0100", "d1_0101"]
 s0000(:d1_, 97..101)            # => ["d1_00097", "d1_00098", "d1_00099", "d1_00100", "d1_00101"]
 s0000(:d1_, 1..5)               # => ["d1_00001", "d1_00002", "d1_00003", "d1_00004", "d1_00005"]

ss

ss o sseq genera una lista di liste (matrice) di nomi di variabili. Specificare una stringa contentente i nome della variabile con i segnaposti #1 e #2 che verranno sotituiti dalle due sequenze numeriche. E’ possibile utilizzare interi (10), range (2..7), vettori ([1,3,5,7,9]). Un numero negativo esclude l’elemento dalla sequenza. Se si utilizza un elemento composito, passare tutto l’argomento come vettore: [true,2..7,-5,-6]. true come secondo argomento, esegue il padding con lo zero. Se lo zero deve essere aggiunto a una sola sequenza, specificare true come primo elemento dell’argomento.

La funzione è utile per generare le liste di variabili nelle tabelle grid.

 ss(string, sequences/ranges/values, sequences/ranges/values)
 ss(string, padding, sequences/ranges/values, sequences/ranges/values)
 ss(string, [padding, sequences/ranges/values], [padding, sequences/ranges/values])

 ss("x1_#1_#2",3,5)                   # => [[:x1_1_1, :x1_1_2, :x1_1_3, :x1_1_4, :x1_1_5], [:x1_2_1, :x1_2_2, :x1_2_3, :x1_2_4, ...]]
 ss("x1_#2_#1",3,5)                   # => [[:x1_1_1, :x1_2_1, :x1_3_1, :x1_4_1, :x1_5_1], [:x1_1_2, :x1_2_2, :x1_3_2, :x1_4_2, ...]]
 ss("x1_#2_#1",3,2..7)                # => [[:x1_2_1, :x1_3_1, :x1_4_1, :x1_5_1, :x1_6_1, :x1_7_1], [:x1_2_2, :x1_3_2, :x1_4_2, ...]]
 ss("x1_#1_#2",[1,3,5,7,9],3)         # => [[:x1_1_1, :x1_1_2, :x1_1_3], [:x1_3_1, :x1_3_2, :x1_3_3], [:x1_5_1, :x1_5_2, ...]]
 ss("x1_#2_#1",3,[2..7,-5,-6])        # => [[:x1_2_1, :x1_3_1, :x1_4_1, :x1_7_1], [:x1_2_2, :x1_3_2, :x1_4_2, :x1_7_2], [:x1_2_3, ...]]
 ss("x1_#2_#1",true,9..12,7..10)      # => [[:x1_07_09, :x1_08_09, :x1_09_09, :x1_10_09], [:x1_07_10, :x1_08_10, :x1_09_10, ...]]
 ss("x1_#2_#1",9..12,[true,7..10])    # => [[:x1_07_9, :x1_08_9, :x1_09_9, :x1_10_9], [:x1_07_10, :x1_08_10, :x1_09_10, ...]]

to

to restituisce l’elenco dei nomi di variabile tra la prima e l’ultima variabile indicata

to(:d30, :d38) # dalla variabile d30 alla d38
to(:d30)       # dalla variabile d30 fino all'ultima
to(nil, :d38)  # dalla prima variabile fino alla d38

:d30.to(:d38)  # anche come metodo di Symbol

like

like restituisce l’elenco dei nomi di variabile che corrispondono all’espressione regolare specificata. Se si passa una stringa o un simbolo, verrà utilizzata come inizio del nome delle variabili.

md like(/^v10013_\d+/)

levels like(/v10180_/) => ["1 per niente d’accordo", "2", "3", "4", "5 completamente d’accordo"]

like(:d7_)
like("d7_")

inc, inc?

inc{} include ed esegue il contenuto di un file nello script.
L’estensione di default è pt2. Notare l’utilizzo delle parentesi graffe e non di quelle tonde.
Se viene fornito solo il nome, il file verrà cercato nella cartella di lavoro, altrimenti nel percorso indicato. I percorsi relativi partono dalla cartella di lavoro.

inc?{} cerca il file nella cartella di lavoro e nelle cartelle genitori della cartella di lavoro e utilizza il primo trovato (non è possibile specificare un percorso).

inc!{} cerca il file anche nelle cartelle di configurazione e di installazione. Utilizza il primo trovato (non è possibile specificare un percorso).

inc{"filename"}
inc{"folder/filename"}
inc{"../../folder/filename"}
inc{"d:/folder/filename"}

inc?{"filename"}

Indipendentemente dalla loro collocazione, anche nei file inclusi, la cartella di lavoro è sempre quella dello script principale.

Le variabili locali definite nel file incluso non sono visibili nello script principale. Utilizzare invece:

• variabili precedentemente definite nello script principale
• variabili di istanza (@var)
• costanti (VAR)
• funzioni (def var)
• l’oggetto setup

included?

included? restituisce true se lo script è stato incluso da un altro script e false se è stato eseguito direttamente.

included_file

included_file restituisce il nome del file incluso o nil.

rep

rep cicla [2] sugli elementi di un array (vettore), di un range o di un hash (array associativo). Esegue il codice contenuto nel blocco passando due argomenti: l’elemento e il suo indice. Per gli hash passa tre argomenti: la chiave, il valore e l’indice. L’indice parte da 1. L’indice può essere tralasciato se non serve. I nomi dei parametri sono arbitrari.

# array generato dalla funzione s con indice
s(:q25_,1..10).rep do |v, i|
  levels v => {1 => "Voto: 1", 10 => "Voto: 10"}
  ord v, "25.#{i}. Per ciascuno ambito dia un giudizio con un voto da 1 a 10\n$vl()"
end

# array generato dalla funzione s senza indice
s(:q31_,1..10).rep do |var|
  levels var => {1 => "Voto: 1", 10 => "Voto: 10"}
end

# array di label con indice
[ "Scuola",
  "Sanita'",
  "Sicurezza",
  "Sviluppo economico",
  "Politica estera",
  "Giustizia",
  "Fisco",
  "Famiglia",
  "Ambiente",
  "Costi della politica" ].rep do |lab, index|
    label "x40.#{index}" => lab
end

# range (su una sola riga)
(1..18).rep { |n| rename s("q9pr_loop_#{n}_q9pr_resp",9) => s("q9_#{n}_",9) }

# hash con indice
{ 2 => "Brand X",
  5 => "Brand Y",
  6 => "Brand Z" }.rep do |num, label, index|
  cat "q5pr_loop_#{num}_q5pr_resp", "Q5.#{index} BRAND CONSIDERATION - #{label}"
end

.each

each cicla sugli elementi di un array (vettore), di un range o di un hash (array associativo). Esegue il codice contenuto nel blocco passando come argomento l’elemento. Per gli hash passa due argomenti: la chiave e il valore. I nomi dei parametri sono arbitrari.

.each_with_index

each_with_index cicla sugli elementi di un array (vettore), di un range o di un hash (array associativo). Esegue il codice contenuto nel blocco passando due argomenti: l’elemento e il suo indice. Per gli hash passa tre argomenti: la chiave, il valore e l’indice. L’indice parte da 0. I nomi dei parametri sono arbitrari.

eachvars

eachvars cicla sui nomi di variabili del dataset attivo.

eachvars do |var|
  label var => get_label(var).strip_tags
end

.expand

Il metodo expand applicato a un Array che contiene sia numeri interi che Range (..) genera un vettore di numeri interi.

[2..5,10,15..19,98,99].expand  # => [2,3,4,5,10,15,16,17,18,19,98,99]

.order

Il metodo order applicato a un elenco (Array) di nomi variabil, restituisce l’elenco ordinato rispetto alle ultime cifre del nome della variabile.

 like("d7_").order
 # => ["d7_1", "d7_2", "d7_3", "d7_4", "d7_5", "d7_6", "d7_7", "d7_8", "d7_9", "d7_10", "d7_99"]

.sample

Il metodo sample applicato a un Array, estrae casualmente un elemento o il numero di elementi indicato.

(1..1000).to_a.sample    # => 973

(1..1000).to_a.sample(5) # => [106, 462, 936, 443, 286]

.to_list

Il metodo to_list applicato a un Array genera una stringa con i vari elementi concatenati dalla virgola.

s(:d7_,1..7).to_list # => "d7_1,d7_2,d7_3,d7_4,d7_5,d7_6,d7_7"

.to_xlsx

Il metodo to_xlsx applicato a un Array o a un Hash salva il contenuto in un nuovo file XLSX.

Argomenti:

• filename: il nome del file da generare
• :header => []: un vettore con le intestazioni delle colonne

sortvars

La funzione sortvars applicata a un elenco di variabili, restituisce lo stesso elenco di variabili ordinato in base alla frequenza. Tiene conto di un eventaule filtro attivo.

• :code => 1: codice da considerare nel conteggio (default 1)
• :ord => :a|:d: direzione dell’ordinamento :a ascendente, :d discendente (default :d)

sortvars(s(:d7_,1..10))

.strip_tags

Il metodo strip_tags applicato a una stringa elimina i tag html.

 label :v1 => get_label(:v1).strip_tags

.style

Il metodo style applicato a una stringa aggiunge un tag html spam all’etichetta per formattare la fiancata delle tabelle.

Classi supportate:

• net
• lev0 .. lev7
• bold

 varnames.zip(levels).each do |varname, level|
   if varname.start_with?("net_")
     label varname => get_label(varname).style("lev#{level-1}", :net)
   else
     label varname => get_label(varname).style("lev#{level-1}")
   end
 end

srand

srand inizializza il generatore di numeri pseudo-casuale del sistema con il valore indicato. Può essere utilizzato per garantire sequenze ripetibili di numeri pseudo-casuali tra diverse esecuzioni del programma. Impostando il seme su un valore noto, i programmi possono essere resi deterministici. Restituisce il valore del seme precedente.

srand 123456789

stop, stoph, stoph!, sh, sh!, stopx, stopx!, sx, sx!

• stop arresta l’esecuzione dello script
• stoph o sh genera un report HTML e arresta l’esecuzione dello script
• stoph! o sh! genera un report HTML, lo apre e arresta l’esecuzione dello script
• stopx o sx genera un report XLSX e arresta l’esecuzione dello script
• stopx! o sx! genera un report XLSX, lo apre e arresta l’esecuzione dello script

Eventuali istruzioni successive nello script devono comunque essere sintatticamente corrette.

msg, todo, done, warn, err, msg!, todo!, done!, warn!

msg, todo, done, warn e err stampano nell’output i testo che li segue. err causa l’interruzione dello script.

Le varianti msg!, todo!, done!, warn! aprono anche una finestra di dialoco.

Il parametro :nodlg => false non fa comparire la finestra di dialogo.

warn "Attenzione controlla il filtro!"

warn! "Attenzione controlla il filtro!"

Le funzioni restituiscono l’ultimo argomento:

value_if :w1, warn("Attenzione: forzo il peso a 1", 1), "sample=2"

fields.to_ptabs_labels

fields.to_ptabs_labels stampa nella finestra di log le istruzioni di pTabs per etichettare le variabili del file di dati.

Argomenti:

• :vars => [varlist]: elenco delle variabili, se omesso stampa tutte le etichette
• :ptabs => 1|2: stampa le istruzioni con la sintassi di pTabs2 (2, il default) o della vecchia versione di pTabs (1)
• :labels => true|false: stampa le istruzioni per le etichette delle variabili (true, il default)
• :levels => true|false: stampa le istruzioni per le etichette dei valori (true, il default)

fields.to_spss_labels

fields.to_spss_labels stampa nella finestra di log le istruzioni SPSS per etichettare le variabili del file di dati.

Argomenti:

• :vars => [varlist]: elenco delle variabili, se omesso stampa tutte le etichette
• :by_val => true|false: stampa le istruzioni variabile per variabile alternando variables labels e values labels (true) oppure un’unica istruzione variables labels per tutte le variabilie seguita da un’istruzione values labels (false, il default)
• :labels => true|false: stampa le istruzioni per le etichette delle variabili (true, il default)
• :levels => true|false: stampa le istruzioni per le etichette dei valori (true, il default)

fields.definitions

fields..definitions stampa nella finestra di log le istruzioni di pTabs per definire le variabili del file di dati.

Argomenti:

• :vars => [varlist]: elenco delle variabili, se omesso stampa tutte le etichette

css

L’output HTML e PDF sono controllati da fogli stile CSS. L’utente può ridefinire i propri fogli stile, ma per operazioni più veloci e/o temporanee di modifica degli stili è possibile inserire delle istruzioni css direttamente nello script tramite l’istruzione css.

# disattiva gli stili dei NET
css << "table td.net { font-weight: normal; }"
css << "table td.lev1, table td.lev2, table td.lev3 { font-style: normal; }"
css << "table td.label.lev1, table td.label.lev2, table td.label.lev3 { padding-left: 6px; }"

css.load

pTabs carica automaticamente i fogli stili con i nomi definiti nei parametri di configurazione. I file vengono cercati nella cartella di installazione di pTabs, nella cartella dell’utente e nella cartella di lavoro.

Con l’istruzione css.load(filename) è inoltre possibile caricare degli ulteriori fogli stile css nello script.

css.load 'my_syle.css'

debug

debug stampa nel log il contenuto di una variabile, di un oggetto o il valore di ritorno di un metodo.

 x = 'info'.yload
 debug x

ruler

ruler stampa nel log un righello.

Argomenti:

• lenght: la lunghezza del righello (default: 100)
• start: il punto di inizio (default: 1)
• :off => n: il numero di caratteri da saltare all’inizio della riga (default: 0)

ruler 54

         1         2         3         4         5
123456789012345678901234567890123456789012345678901234

num2col, col2num, xcols

Funzioni per le colonne di un foglio elettronico.

num2col(1)    # => "A"
col2num("A")  # => 1
num2col(76)   # => "BX"
col2num("BX") # => 76
xcols(12)     # => ["A", "B", "C", "D", "E", "F", "G", "H", "I", "J", "K", "L"]

pad0

Trasforma un numero intero in stringa e lo allinea a destra riempiendo a sinistra con gli zeri necessari fino a ottenere il numero di caratteri indicati.

year = 2023
wave = 5

name "Tavole_" + year.to_s + wave.pad0(2) # => "Tavole_202305"
name "Tavole_#{year}" + wave.pad0(2)      # => "Tavole_202305"
name "Tavole_#{year}#{wave.pad0(2)}"      # => "Tavole_202305"

Note

[1]	I caratteri # e . possono essere utilizzati solo nelle stringhe, non nei simboli. Il carattere # non è un carattere valido nei nomi di variabile. Se presente nel file originale, viene convertito in . o _ a secondo delle impostazioni di dot_to_underscore e underscore_to_dot.

[2]	Un ciclo di ripetizioni può comunque essere realizzato utilizzando uno qualsiasi dei costrutti che mette a disposizione Ruby. Ricordarsi comunque che gli indici in Ruby partodo da 0. rep equivale al metodo each_with_index con l’indice incrementato di 1.