Funzioni di utilità

Le seguenti funzioni di utilità sono disponibili all’interno del blocco di istruzioni del report.

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. 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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
 s(string, sequences/ranges/values/names)
 s(string, padding, sequences/ranges/values/names)
 s([pre,post], padding, sequences/ranges/values/names)

 s(:x_, 5)                            # => x_1 x_2 x_3 x_4 x_5
 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([: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

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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
 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", ...

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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
 # 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

rev

rev è un metodo applicabile a Array e Range che inverte l’ordine degli elementi.

1
2
 (1..7).rev          # => [7, 6, 5, 4, 3, 2, 1]
 s(:d1_,5).rev       # => ['d1_5', 'd1_4', 'd1_3', 'd1_2', 'd1_1']

ids

ids(indici) è un metodo applicabile a Array. Restituisce un vettore con solo gli elementi con gli indici indicati.

1
2
 ('A'..'Z').to_a.ids(2,17)     # => ['C', 'R']
 get_levels(:d5).ids(1,2,4,5)  # => etichette dei livelli 1, 2, 4 e 5 della variabile d5

in_groups_of

in_groups_of(n) è un metodo applicabile a Array. Raggruppa gli elementi in gruppi restituendo un vettore di vettori.

1
2
varlist = ["q5_1_1", "q5_1_2", "q5_1_3", "q5_1_4", "q5_2_1", "q5_2_2", "q5_2_3", "q5_2_4"]
varlist.in_groups_of(4)  # => [["q5_1_1", "q5_1_2", "q5_1_3", "q5_1_4"], ["q5_2_1", "q5_2_2", "q5_2_3", "q5_2_4"]]

pr

pr stampa nel log il valore dell’oggetto e restituisce il valore.

1
md s(:v1_,3).pr         # => [:v1_1, :v1_2, :v1_3]

common

common(string) è un metodo applicabile a String che confronta due stringhe e restituisce la sottostringa comune.

1
2
3
4
5
label :v1_2 => get_label(:v1).common(get_label(:v2))

get_label(:v1)      # => "Gradimento prodotto XXX"
get_label(:v2)      # => "Gradimento prodotto YYYYY"
get_label(:v1_2)    # => "Gradimento prodotto"

log_width

Imposta il numero di colonne dell’output di R.

1
 log_width 200

stop! / start!

Sospende/riavvia l’esecuzione delle istruzioni dello script all’interno del blocco di un report.

stop! sospende l’esecuzione da quel punto dello script in avanti. Le istruzioni sospese devono comunque essere sintatticamente corrette.

start! riavvia l’esecuzione.

Si possono inserire più istruzioni stop! e start! nello script. Le istruzioni che vengono ‘saltate’ devono comunque essere sintatticamente corrette.

r.exec o r <<

E’ possibi eseguire direttamente istruzioni R. A questo proposito è da notare che il data frame utilizzato da pTabs è chiamato dfr.

1
2
3
4
5
6
7
8
 r.exec "istruzione R"
 r << "istruzione R"

 r << <<-END
   istruzione R
   istruzione R
   ...
 END

r.source

Carica ed esegue un file di istruzioni R.

1
2
3
 r.source "r_file1.R"
 r.source "prog/r_file2.R"
 r.source 'c:\rscripts\r_file3.R'

$p

Contiene un riferimento all’oggetto report corrente. E’ utile per eseguire metodi del report all’interno di un altro contesto, per esempio in un’unione di tabelle.

1
2
3
4
5
6
7
8
 htjoin "Tabella di confronto di tre ponderazioni", "PONDERAZIONI" do
   $p.weight.by :ipf1
   md s(:d7_,1..10), "Peso 1"
   $p.weight.by :ipf2
   md s(:d7_,1..10), "Peso 2"
   $p.weight.by :ipf3
   md s(:d7_,1..10), "Peso 3"
 end

In questo caso può essere direttamente utilizzata l’istruzione weight!.

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.

1
2
3
4
 # 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.table, css.chart, css.map, css.doc

Specifica delle istruzioni css solo per l’ultima tavola/grafico/mappa/testo prodotta. Le istruzioni vanno poste dopo l’istruzione che produce la tabella/grafico/mappa/testo. L’istruzione css viene preceduto dal selettore di tabella/grafico/mappa/testo.

1
2
3
4
5
 css.table << " td.net { font-weight: normal; color: blue }"
 # div#ptabs > div.table table#t1 td.net { font-weight: normal; color: blue }

 css.chart << "table.chart.gauge svg > g > circle:nth-child(1) { fill: #4682B4; stroke: #616161; stroke-width: 1; }"
 # div#ptabs > div.chart table#t3 table.chart.gauge svg > g > circle:nth-child(1)

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.

1
css.load 'my_syle.css'

debug

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

1
2
 x = 'info'.yload
 debug x

Scrittura e lettura di informazioni

Gli Hash ({:key => value}) dispongono di alcuni metodi che consentono la scrittura e la lettura del loro contenuto in formato YAML e JSON.

Tale funzione è utile, per esempio, per configurare uno script tramite un file esterno o per passare dati tra diversi script.

ydump e jdump scrivono l’Hash rispettivamente su file YAML e JSON. Se il file esiste viene sovrascritto.

yload e jload caricano l’Hash rispettivamente da file YAML e JSON. Se il file non esiste compare un messaggio di warning, ma l’esecuzione prosegue senza problemi.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
 # Scrittura file YAML

 rake_result = rake ...

 { :eff => rake_result.efficiency,
   :min => rake_result.min,
   :max => rake_result.max }.ydump 'ponderazione'

 # genera il file: ponderazione.ydump
 ---
 :eff: 88.2
 :min: 0.3576
 :max: 2.0513

 # Scrittura file JSON

 {:d5 => get_counts(:d5)}.jdump 'd5'

 # genera il file: d5.json
 {"d5":[[1,"Non risponde",20.0],[2,"Per niente d'accodo",16.0],[3,"Poco d'accordo",83.0],
 [4,"Abbastanza d'accordo",95.0],[5,"Molto d'accordo",56.0]]}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
 # Lettura file YAML

 # info.yaml
 ---
 :data_file: dataFileName
 :titolo: Titolo report
 :filtro:
   :sesso: 1

 # nello script:
 x = 'info'.yload
 # accedo agli elementi dell'Hash x con l'operatore []
 title x[:titolo]
 spss.open x[:data_file]
 filter x[:filtro]

 # oppure, utilizzando la funzione defvar, le variabili saranno direttamente disponibili nello script
 defvar 'info'.yload
 title titolo
 spss.open data_file
 filter filtro

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 della classe Array con l’indice incrementato di 1.